<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.11"/>
<title>ArNetworking: ArNetworking</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtreedata.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript">
  $(document).ready(initResizable);
  $(window).load(resizeHeight);
</script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 56px;">
  <td id="projectalign" style="padding-left: 0.5em;">
   <div id="projectname">ArNetworking
   &#160;<span id="projectnumber">dev20180125</span>
   </div>
  </td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.11 -->
  <div id="navrow1" class="tabs">
    <ul class="tablist">
      <li class="current"><a href="index.html"><span>Main&#160;Page</span></a></li>
      <li><a href="pages.html"><span>Related&#160;Pages</span></a></li>
      <li><a href="annotated.html"><span>Classes</span></a></li>
      <li><a href="files.html"><span>Files</span></a></li>
      <li><a href="examples.html"><span>Examples</span></a></li>
    </ul>
  </div>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
  <div id="nav-tree">
    <div id="nav-tree-contents">
      <div id="nav-sync" class="sync"></div>
    </div>
  </div>
  <div id="splitbar" style="-moz-user-select:none;" 
       class="ui-resizable-handle">
  </div>
</div>
<script type="text/javascript">
$(document).ready(function(){initNavTree('index.html','');});
</script>
<div id="doc-content">
<div class="header">
  <div class="headertitle">
<div class="title">ArNetworking </div>  </div>
</div><!--header-->
<div class="contents">
<div class="toc"><h3>Table of Contents</h3>
<ul><li class="level1"><a href="#overviewintro">Introduction</a></li>
<li class="level1"><a href="#Servers">Servers</a><ul><li class="level2"><a href="#ServerModes">Server Modes</a></li>
<li class="level2"><a href="#SimpleServerCommands">Simple Server Commands</a></li>
<li class="level2"><a href="#ARNLServerClasses">Networking in ARNL and SONARNL</a></li>
<li class="level2"><a href="#PreMadeServices">Standard Services Available in ArNetworking</a></li>
</ul>
</li>
<li class="level1"><a href="#Clients">Clients</a></li>
</ul>
</div>
<div class="textblock"><p>MobileRobots <b>Advanced Robotics Networking Infrastructure (ArNetworking)</b> Developer's API Reference Manual<br />
 Copyright 2005 ActivMedia Robotics, LLC. All rights reserved.<br />
 Copyright 2006, 2007, 2008, 2009, 2010 MobileRobots Inc. All rights reserved.<br />
 Copyright 2011, 2012, 2013, 2014, 2015 Adept Technology. All rights reserved.</p>
<p>ArNetworking is an extensible networking protocol and infrastructure. It is used to add networking services to a robot control program, integrated with ARIA and other MobileRobots software libraries.</p>
<p>For a list of requests clients can send to servers, with example code of making request, receiving replies, and how a server can respond to requests, see <a class="el" href="RemoteRequestAPI.html">ArNetworking Remote Request API List</a>. For more description of how ArNetworking works and what is included in the ArNetworking library, see below.</p>
<h1><a class="anchor" id="overviewintro"></a>
Introduction</h1>
<p>ArNetworking is used in a client-server architecture. A client issues <em>requests</em> to a server to issue a single command the server, or to start retrieving data from the server at a specified time interval. A request type is identified by a short string.</p>
<p>A client may be an operator's graphical interface, or a component requiring off-board resources (such as a multi-robot planning system, for example). However, a program onboard the robot could also implement a client, and issue requests to an offboard server (e.g. to retrieve data from a central database). It is also possible for an ArNetworking server to also include a client interface, for example to relay data (e.g. sensor or image data received and processed by a second computer).</p>
<p>In a typical application, however, a program acting as the server runs on the robot's computer, and uses ARIA (and possibly ARNL or SONARNL) to control the robot. This creates a three-tier system: the robot itself is the first tier, and acts as a "robot server" to a program on its onboard computer which is simultaneously a "robot client" and an "ArNetworking server". Offboard ArNetworking clients are the final tier. This three-tier architecture allows a tight, reliable control loop between the robot control program on the onboard computer, and removes higher level user-interface clients accross the potentially unreliable network, protecting the more critical robot control program, and providing a more immediate and flexible user interface.</p>
<p>ArNetworking can use both TCP and UDP.</p>
<div class="image">
<img src="ArNetworking_overview.png" alt="ArNetworking_overview.png"/>
<div class="caption">
Abstract overview of ArNetworking in a typical client-server configuration with one client issuing requests to a server</div></div>
<h1><a class="anchor" id="Servers"></a>
Servers</h1>
<p>An ArNetworking server program is comprised of an <a class="el" href="classArServerBase.html" title="Base server for all networking services. ">ArServerBase</a> object, to which callback functors are added for each request type you wish to handle using <a class="el" href="classArServerBase.html#a2df604c980c35140f69d35362a3403f2" title="Adds a callback to be called when requests for some data are recieved. ">ArServerBase::addData()</a>, or an <a class="el" href="classArServerDataProvider.html" title="Tool to easily obtain and provide changing data values from an acessor method of a class...">ArServerDataProvider</a> object. These callbacks or provider objects are often encapsulated in handler classes. The ArNetworking library provides a variety of prewritten classes for providing current state information about the robot and devices, for teleoperation control, and more (these are classes in the ArNetworking library typically beginning with the prefix ArServerHandler... or ArServerInfo...)</p>
<p><a class="el" href="classArServerBase.html" title="Base server for all networking services. ">ArServerBase</a> creates a background thread to asyncronously accept client connections and receive clients' requests, while your main program thread executes simultaneously. (This thread runs in a loop, and you may add general-purpose callback functors to be invoked each cycle of this loop using <a class="el" href="classArServerBase.html#a1dd6a24a2047f58b072e81c0738422d5" title="Add a callback to be called at every cycle. ">ArServerBase::addCycleCallback()</a>, if desired. This is useful since these callbacks are invoked within the server's thread.)</p>
<p>An <a class="el" href="classArServerDataProvider.html" title="Tool to easily obtain and provide changing data values from an acessor method of a class...">ArServerDataProvider</a> object handles requests from clients, obtains a simple value or list of values from a user-supplied callback or pointer, and sends the value to the client as a reply. See documentation for <a class="el" href="classArServerDataProvider.html" title="Tool to easily obtain and provide changing data values from an acessor method of a class...">ArServerDataProvider</a> for more details.</p>
<p>You can also directly handle requests yourself, if you need to parse arguments provided with the client's request, or to assemble a reply packet which is more complex than can be handled automatically by <a class="el" href="classArServerDataProvider.html" title="Tool to easily obtain and provide changing data values from an acessor method of a class...">ArServerDataProvider</a>. A callback functor for a request, when invoked, receives an <a class="el" href="classArNetPacket.html" title="our packet for the network stuff ">ArNetPacket</a> object containing the request's payload data, and a pointer to an object used to send a reply packet to the client.</p>
<p>To simplify server program setup, a helper class <a class="el" href="classArServerSimpleOpener.html" title="Set up and open an ArNetworking server. ">ArServerSimpleOpener</a> is available.</p>
<p>The default port number for an <a class="el" href="classArServerBase.html" title="Base server for all networking services. ">ArServerBase</a> object to open is 7272, though an alternate port number may be used via a command line argument to the program, or specified in the <a class="el" href="classArServerBase.html" title="Base server for all networking services. ">ArServerBase</a> constructor.</p>
<p>For a concise list of all requests handled by various server classes in ArNetworking, see <a class="el" href="RemoteRequestAPI.html">ArNetworking Remote Request API List</a>.</p>
<h2><a class="anchor" id="ServerModes"></a>
Server Modes</h2>
<p>ArNetworking also provides a system of robot control mode classes (see <a class="el" href="classArServerMode.html" title="A mode for controlling the robot (only one active) ">ArServerMode</a> base class). The server may only be in one mode at a time, each of which enables and disables ARIA <a class="elRef" doxygen="/home/reed/amrsw/Aria/docs/Aria.tag:../../docs/" href="../../docs/classArAction.html">ArAction</a> objects.</p>
<h2><a class="anchor" id="SimpleServerCommands"></a>
Simple Server Commands</h2>
<p>ArNetworking includes the <a class="el" href="classArServerHandlerCommands.html" title="Class for having commands that can be called easily on the client. ">ArServerHandlerCommands</a> class that provides a very simple API for simple "command" requests: requests, perhaps with a few parameters, that simply perform some action or change some state, and have no data to reply with. Callback functors added for requests via an <a class="el" href="classArServerHandlerCommands.html" title="Class for having commands that can be called easily on the client. ">ArServerHandlerCommands</a> object do not receive the request packet data, so they do not need to do any decoding of that data. Additionally, <a class="el" href="classArServerHandlerCommands.html" title="Class for having commands that can be called easily on the client. ">ArServerHandlerCommands</a> keeps a list of requests that it manages, which is available to clients. ArNetworking includes some prewritten classes (ArServerSimpleCom*) which simply add new commands to an <a class="el" href="classArServerHandlerCommands.html" title="Class for having commands that can be called easily on the client. ">ArServerHandlerCommands</a> object and encapsulate their request callbacks.</p>
<p>For example, MobileEyes queries this list on connection, and if some of these simple commands are available, it makes a menu in the toolbar called Custom Commands accessible. This is a way to make special features of your custom robot server application controllable from MobileEyes.</p>
<h2><a class="anchor" id="ARNLServerClasses"></a>
Networking in ARNL and SONARNL</h2>
<p>The ARNL and SONARNL libraries contain some ServerHandler/ServerInfo classes that implement useful server requests, as well as server Mode classes.</p>
<h2><a class="anchor" id="PreMadeServices"></a>
Standard Services Available in ArNetworking</h2>
<p>These are some of the pre-written services which are available in the ArNetworking library for you to use in your server programs. To use these services, your server program typically only needs to create and retain an instance of the class, though some require some additional setup.</p>
<p>For a concise list of all requests handled by various server classes in ArNetworking, see <a class="el" href="RemoteRequestAPI.html">ArNetworking Remote Request API List</a>.</p>
<ul>
<li>
<a class="el" href="classArServerInfoRobot.html" title="Server component providing basic robot status information to clients. ">ArServerInfoRobot</a> - Supplies clients with basic robot state information (current position and velocity, active server mode and status, battery voltage) </li>
<li>
<a class="el" href="classArServerInfoSensor.html" title="Service providing clients with data from range sensors. ">ArServerInfoSensor</a> - Supplies clients with current sensor readings (Sonar or Laser) </li>
<li>
<a class="el" href="classArServerHandlerMap.html" title="Service providing the contents of a map file to the client. ">ArServerHandlerMap</a> - Supplies clients with data from an <a class="elRef" doxygen="/home/reed/amrsw/Aria/docs/Aria.tag:../../docs/" href="../../docs/classArMap.html">ArMap</a> </li>
<li>
<a class="el" href="classArServerInfoDrawings.html" title="Service to provide clients with information about graphical figures to be displayed with the map...">ArServerInfoDrawings</a> - Supplies clients with a set of graphical figures to be displayed with the map (e.g. point sets, lines, circles) </li>
<li>
<a class="el" href="classArServerHandlerCamera.html" title="Accepts and processes camera pan/tilt/zoom requests from the client, and provides information about t...">ArServerHandlerCamera</a> - Allows clients to control a pan-tilt camera and provides information about its current position </li>
<li>
<a class="el" href="classArServerInfoStrings.html" title="This will set up strings to send to MobileEyes so that server developers can easily add more informat...">ArServerInfoStrings</a> - A set of general purpose key,value string pairs obtained from a global table (See <a class="elRef" doxygen="/home/reed/amrsw/Aria/docs/Aria.tag:../../docs/" href="../../docs/classAria.html#af1d44610d83bc5112040bc7d4c602ba9">Aria::getInfoGroup()</a>) </li>
<li>
<a class="el" href="classArServerHandlerMapping.html" title="Class that handles the starting, stopping, and status of mapping. ">ArServerHandlerMapping</a> - Allows clients to trigger collection of laser scan data for use in making a map later (with the Mapper3 application) </li>
<li>
<a class="el" href="classArServerFileToClient.html" title="Gets files from the server. ">ArServerFileToClient</a>, <a class="el" href="classArServerFileFromClient.html" title="Puts files onto the server. ">ArServerFileFromClient</a>, <a class="el" href="classArServerFileLister.html" title="Provides a list of files to clients. ">ArServerFileLister</a> - Allows clients to upload and download files from the server filesystem </li>
</ul>
<h1><a class="anchor" id="Clients"></a>
Clients</h1>
<p>A client program is comprised of an <a class="el" href="classArClientBase.html" title="The base client class. ">ArClientBase</a> object which must be connected to a server via a network socket (either TCP or the default, UDP). The server is identified by network hostname and port number, which may be given through <a class="el" href="classArClientBase.html" title="The base client class. ">ArClientBase</a> API or in the program command line arguments. Requests are made to the server via <a class="el" href="classArClientBase.html#a0a36a40fe2598eb214368ae8c3a26ca1" title="Request some data every mSec milliseconds. ">ArClientBase::request()</a>, <a class="el" href="classArClientBase.html#a2dcd11daf8d2045d460b83733e6932d0" title="Request some data (or send a command) just once. ">ArClientBase::requestOnce()</a>, or using an <a class="el" href="classArClientDataReceiver.html" title="A client program may use this to receive responses to data requests and pass the received data to a p...">ArClientDataReceiver</a> object.</p>
<p>If an <a class="el" href="classArClientDataReceiver.html" title="A client program may use this to receive responses to data requests and pass the received data to a p...">ArClientDataReceiver</a> object is used, it will make requests at a specified interval, receive any replies, automatically parse some simple data types provided in the reply from the server, and call a user-supplied callback function, or just store the value(s). See documentation for <a class="el" href="classArClientDataReceiver.html" title="A client program may use this to receive responses to data requests and pass the received data to a p...">ArClientDataReceiver</a> for more details.</p>
<p>You can also directly make requests and handle reply packets yourself, if you need to parse a reply packet that is more complex than can be handled automatically by ArClientDataReciver.</p>
<p><a class="el" href="classArClientBase.html" title="The base client class. ">ArClientBase</a> creates a background thread to asyncronously communicate with the server.</p>
<p>A client may query a server to discover if a data request type is available using <a class="el" href="classArClientBase.html#a873a731b968b4e3359c60d592122770b" title="Sees if this data exists. ">ArClientBase::dataExists()</a>.</p>
<p>To simplify client program setup and connection to a server, a helper class <a class="el" href="classArClientSimpleConnector.html" title="This will let you connect to different hosts, ports, and with different users and passwords more easi...">ArClientSimpleConnector</a> is available.</p>
<p>For a concise list of all requests handled by various server classes in ArNetworking, see <a class="el" href="RemoteRequestAPI.html">ArNetworking Remote Request API List</a>.</p>
<p>See example programs in the examples directory for complete example programs. </p>
</div></div><!-- contents -->
</div><!-- doc-content -->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
  <ul>
    <li class="footer">Generated by
    <a href="http://www.doxygen.org/index.html">
    <img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.8.11 </li>
  </ul>
</div>
</body>
</html>
